<html>
<head>
<title>UI Forms enhancements in 3.3 M5</title>
</head>
<body>
<h1>UI Forms enhancements in release 3.3</h1>
<address>Dejan Glozic and Kimberley Peter, 01/22/2007</address>
<h2>Background</h2>
<p>The document is meant to enumerate various enhancements that will be 
available in Eclipse Platform release 3.3 from milestone 5. The readers are assumed 
to be familiar with Forms in general and have some working experience with them. 
If that is not the case, a good place to start would be Eclipse article:
<a target="_blank" href="http://www.eclipse.org/articles/Article-Forms/article.html">
Eclipse Forms: Rich UI for Rich Client Applications</a> as well as
<a href="http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/guide/forms.htm">
online documentation</a>.</p>
<p>Most of the features listed in this document will be available in the 
integration builds leading to M5 and can be used with the caveat that there is a 
small change that APIs can change before they are frozen in the M5 stable build. 
We make these changes only if absolutely necessary and not without the prior 
warning on the mailing list.</p>
<h2>Changes related to forms heading</h2>
<p>The majority of changes in 3.3 are related to the way forms heading is 
handled. Much more can be done now in the heading and the changes that were 
first introduced in 3.2 are clarified and evolved further.</p>
<h3>Title rendering</h3>
<p>As before, the heading area is initially rendered using the overall 
background color of the form. Clients still have an option to decorate this area 
using two mutually exclusive approaches: by providing a background image or by 
providing an array of colors to render a gradient. However, either approach is 
problematic when it comes to making the design hold on all the platforms and 
windowing systems Eclipse can run on. For this reason, we have elected to 
provide one combination of colors for title background rendering that will work 
well everywhere. The color used to render the title are stored in the <code>
FormColors</code> class under the following keys (defined in <code>IFormColors</code> 
interface):</p>
<ul>
	<li><code>H_GRADIENT_START</code></li>
	<li><code>H_GRADIENT_END</code></li>
	<li><code>H_BOTTOM_KEYLINE1</code></li>
	<li><code>H_BOTTOM_KEYLINE2</code></li>
</ul>
<p align="center"><img border="0" src="gradient.png" width="667" height="45"></p>
<p>These colors are computed by starting from system colors as provided by <code>
SWT</code>, then blending them with the background at various degrees depending 
on the windowing system/skin employed. They are guaranteed to work well 
everywhere Eclipse runs, including accessibility use cases such as 'high 
contrast black' and similar. Nevertheless, in order to turn this rendering on, 
you need to call <code>FormToolkit.decorateFormHeading(Form)</code>.</p>
<p>The decision to use the provided rendering should mostly depend on what is in 
the header of your form. If all you do is set the title, you should probably 
leave the form without it. If, on the other hand, you use heading tool bar, 
heading client, or use new message handling, it may be beneficial to decorate 
the title area in a stronger way using the provided method.</p>
<h3>Layout changes</h3>
<p>As first introduced in 3.2, forms can now have either one or two-row header. 
As before, it is the head client that causes the form to switch to the two rows. 
However, while in 3.2 head client was position on the same raw as the title, in 
3.3 head client is pushed to the second row. Tool bar now stays in the same raw 
as the title all the time. This change is a side-effect of the changes in 
message handling. There is nothing you need to do to react to the change, but it 
will affect your forms if you chose to take advantage of the 3.2 API. Since the 
head client has the entire second row for itself, this will be a good thing in 
most cases.</p>
<p align="center"><img border="0" src="two-rows.png" width="673" height="98"></p>
<p>Although we just claimed that tool bar stays on the same row, there is 
actually an exception. A new API <code>Form.setToolBarVerticalAlignment(int)</code> 
allows for setting the alignment to <code>SWT.BOTTOM</code> and therefore 
placing the tool bar on the second row. By default, this setting is <code>
SWT.TOP</code>. If you know that the head client will not occupy the entire 
width of the space it has for itself, you can push the tool bar down to be 
closer to the form body.</p>
<p align="center">
<img border="0" src="two-rows-bottom.png" width="673" height="97"></p>
<h3>Message handling</h3>
<p>In 3.2, we introduced methods to show typed messages in form heading. The 
messages of types defined in <code>org.eclipse.jface.dialogs.IMessageProvider</code> 
were shown in an animated tray that would overlap the portion of the header when 
visible. We have decided that in many situations the message may be obstructing 
the useful widgets. If the problem is caused by the controls in the head client, 
the message tray would obstruct the very controls that are the cause of the 
message's appearance.</p>
<p>In 3.3, the message is now shown next to the title text. In the normal 
layout, it will use the area between the title and the tool bar (if used) or the 
right edge of the header. As before title text will wrap if there is not enough 
space to display it on one row. In contrast, message text will shrink and 
replace portion of the text with ellipses (...). The full text will be available 
as a tool tip (similar to other places in the workbench).</p>
<p>In addition to showing the text of the message, the image appropriate for the 
message type (error, warning, information) will be shown before the title. If 
there is an image already, it will replace the image until the message is reset. 
The text of the message will also indicate the message type. We have chosen 
fixed system colors (<code>SWT.COLOR_RED</code> for errors and <code>
SWT.COLOR_DARK_YELLOW</code> for warnings) because they work equally well on all 
windowing systems and color combinations we tested.</p>
<p>By default, messages are rendered as static text. If a hyperlink handler is 
added to <code>Form</code> using the new API <code>
Form.addMessageHyperlinkListener(IHyperlinkListener)</code>, the message text 
will be rendered using a hyperlink and the handler will be notified about its 
standard hyperlink events.</p>
<p align="center">
<img border="0" src="message-handling.png" width="673" height="92"></p>
<p>Also see the section on message manager below.</p>
<h3>Image priority</h3>
<p>The area to the left of the title (in LTR locales) is reserved for the form 
image. This area is only used if the image needs to be displayed. In 3.3, this 
area is shared by three potential image groups, in increasing priority:</p>
<ol>
	<li>No image</li>
	<li>Title image set using <code>Form.setImage(Image)</code> API</li>
	<li>Message image (error, warning, information) when message is set</li>
	<li>Busy animation when <code>Form.setBusy(true)</code> is called</li>
</ol>
<p>The appearance of image of any priority when the image of lower priority is 
not already present will cause the form to reflow. In extreme cases, the reduced 
space to render the title may cause the title to wrap, pushing the form body 
down. Keep this in mind if layout stability is important to you.</p>
<h3>Drop-down menu</h3>
<p>In addition to the tool bar manager, a new menu manager has been added to 
forms in 3.3. It is accessible through the new API <code>Form.getMenuManager()</code>. 
When this manager is not empty, a drop-down arrow will appear next to the title 
bar and clicking on it will open the managed menu. The same menu will also 
available as a pop-up menu anywhere on the title and the title image.</p>
<p align="center"><img border="0" src="drop-down.png" width="667" height="95"></p>
<h3>Drag and drop support</h3>
<p>There are use cases when form title represents an object that other workbench 
parts can interact with. In 3.3, we added the ability to support dragging of the 
title into these targets, as well as having the title serve as a drop target for 
the compatible objects. New APIs <code>Form.addDragSupport</code> and <code>
Form.addDropSupport </code>are added to handle this scenario.</p>
<p>When drag and drop support is activated by using the new APIs, title area is 
rendered differently. A border is painted around the title in two colors: 
moderately dark when the mouse is in the vicinity of the title, and dark when it 
is directly over it. We added this visual feedback to indicate the user that the 
title can be manipulated directly. The colors for this indication are part of 
OS/skin dependent color computation and shows well on all the platforms we 
tested it on.</p>
<p align="center"><img border="0" src="dnd1.png" width="334" height="91"></p>
<p align="center"><img border="0" src="dnd2.png" width="292" height="89"></p>
<h2>Changes related to sections</h2>
<h3>New colors</h3>
<p>A new color computation algorithm is used for all colors allocated by<code> 
FormColors</code> class. In addition, rendering of sections when <code>TITLE_BAR</code> 
style is used has been slightly revised. Section headers are now using the same 
color as the form title, which is also applied to the toggle button.</p>
<p align="center"><img border="0" src="section.png" width="665" height="605"></p>
<h3>Section title bar rendering when text client is present</h3>
<p>When some sections on a page have text client (a control that can be placed 
in the section title bar on the right), two problems arise:</p>
<ol>
	<li>Sections that use <code>TITLE_BAR</code> style have the envelope and the 
	gradient painted to include the text client, causing the title bar to be 
	taller</li>
	<li>Taller title bar pushes description and/or the section client down</li>
</ol>
<p>Starting from release 3.3 M5, this problem has been addressed in two steps:</p>
<ol>
	<li>Gradient and envelope for the sections using the <code>TITLE_BAR</code> 
	style are now painted without taking text client into account. This results 
	in a uniform decoration height that is only controlled by the chosen font 
	for the title text.</li>
	<li>The description and/or the section body are still pushed down to 
	accommodate the text client. However, it is possible to use public variables
	<code>ExpandableComposite.clientVerticalSpacing</code> and <code>
	ExpandableComposite.descriptionVerticalSpacing</code> to compensate for the 
	difference so that the rest of the content in side-by-side sections lines 
	up.</li>
</ol>
<p>Since the difference between text and text client heights is dynamic, it is 
not possible to pick a 'magic number' to correct the vertical alignment issues 
in a portable way. For that reason, a new method has been added to <code>
ExpandableComposite</code> - <code>getTextClientHeightDifference()</code>. This 
method will compute the currently valid difference that can be applied as 
described above. Note that making modifications to the text client or changing 
the text font invalidates this value and the method must be called again.</p>
<p>The following sample code shows the application of this method for the 
picture below:</p>
<pre>		Section s1 = createTableSection(form, toolkit, &quot;First Table Section&quot;, true);
		Section s2 = createTableSection(form, toolkit, &quot;Second Table Section&quot;, false);
		s2.descriptionVerticalSpacing += s1.getTextClientHeightDifference();</pre>
<p>As a result, the description of the section <code>s2</code> has been pushed 
down to compensate for the tool bar set as a text client of the section <code>s1</code>:</p>
<p align="center">&nbsp;<img border="0" src="text-client-height.png" width="673" height="264"></p>
<h2>Shared-header form editor</h2>
<p>In most implementations of the multi-page form editor, each page contained a 
separate form with its own title and other heading controls. There is a use case 
for an editor that has multiple pages with one fixed header. In order to support 
this use case, a new class has been added in 3.3 called <code>
SharedHeaderFormEditor</code>. This class extends <code>FormEditor</code> and 
configures is such that the tabbed folder containing pages is placed inside a 
managed form's body, leaving the heading unaffected by page changes. </p>
<p>The common header is configured by extending the class and implementing the 
protected method <code>createHeaderContents(IManagedForm headerForm)</code>. The 
header form is included in the life cycle management of the editor (refresh, 
commit etc.). For this reason, it is recommended to wrap the head client in an
<code>IFormPart</code> and register it with the header form in case head client 
is used. This will ensure that the controls in the head client that can make the 
editor dirty are included in the life cycle management.</p>
<p>Since the header form takes responsibility of the common header, form pages 
that are normally added to this editor must not have the heading themselves. 
This is easily accomplished by not setting the title on individual pages' forms 
or otherwise calling any other method related to the heading.</p>
<p align="center">
<img border="0" src="shared-header.png" width="667" height="625"></p>
<h2>Message Manager</h2>
<p>A new manager is now accessible via the <code>IManagedForm</code> interface 
that makes message management in forms much easier. The manager is available as 
an interface (<code>IMessageManager</code>) and has the following roles:</p>
<ol>
	<li>Manages multiple messages - shows a summary message with the highest 
	type, as well as details as a tool tip</li>
	<li>Provides for adding and removing messages associated with controls on 
	the form</li>
</ol>
<p>The message manager uses JFace support for control decoration to render the 
appropriate image near controls that have messages associated with them. What 
makes message manager convenient is that clients only manipulate messages and 
message types, while the manager handles control decoration at the SWT/JFace 
level. </p>
<p>Clients who want to take advantage of this new facility should refrain from 
setting messages directly using Form APIs and use the manager instead. There are 
methods to add and remove general purpose messages, as well as those associated 
with controls. The manager will keep track of all of them and provide a suitable 
summary message in the header. Clients who use form-based multi-page editors 
already have managed form instances in the pages. All you need to do is ask for 
the manager instance and use it.</p>
<p align="center">
<img border="0" src="message-manager.png" width="669" height="248"></p>
<p align="left">If message label is configured to be a hyperlink, <code>href</code> 
property of the hyperlink event is set to be an array of <samp>IMessage</samp> 
objects that form the summary message. This array is used internally to compose 
the tool tip text. Clients can also use this information to do interesting 
things. For example, a lightweight window can be shown with individual messages 
as hyperlinks, allowing users to go to each one (this feature makes much more 
sense for shared-header editor described earlier, where the error may have 
occurred on a currently inactive page). Another possible use of this data can be 
to offer the user to automatically fix the errors if possible.</p>
<p align="center">
<img border="0" src="message-array.png" width="708" height="223"></p>
<h2>API deprecation and cleanup</h2>
<p>The most significant change in 3.3 is that we moved all the color constants 
into <code>IFormColors</code> interface. The existing constants in <code>
FormColors</code> are now deprecated since they are just pointing at the 
matching constants in <code>IFormColors</code>.</p>
<p>All new APIs are marked using '@since 3.3' in javadoc. Go to the source code 
in the Eclipse builds for details.</p>
</body>
</html>
